<!--
/**
 * @file DBXml.html
 * @author Alejandro Dario Simi
 * @date $Date: 2013-07-24 01:55:33 +0000 (Wed, 24 Jul 2013) $
 *
 * $Id: DBXml.html 99 2013-07-24 01:55:33Z daemonraco@gmail.com $
 * $URL: http://wcomix.googlecode.com/svn/trunk/docs/DBXml.html $
 */
-->
<html>
	<head>
		<title>Database XML Specs</title>
		<script type="text/javascript" src="jquery-1.8.0.min.js"></script>

		<script type="text/javascript" src="SyntaxHighlighter/scripts/shCore.js"></script>
		<link type="text/css" rel="stylesheet" href="SyntaxHighlighter/styles/shCoreEclipse.css"/>
		<link type="text/css" rel="stylesheet" href="SyntaxHighlighter/styles/shThemeEclipse.css"/>
		<script type="text/javascript">SyntaxHighlighter.all();</script>

		<link rel="stylesheet" type="text/css" href="docs.css"/>
		<script type="text/javascript" src="docs.js"></script>
	</head>
	<body>
		<div class="Section">
			<span class="Title">Table Of Contents</span>
			<div class="TableOfContents"></div>
		</div>
		<div class="Section">
			<span class="Title">XML System</span>
			<div class="Paragraph">
				<p>wcomix has an internal way to manage database specifications based on XML file. Instead of having a bunch of
				queries to run on installation, it holds a bunch of XML files and through them it creates the appropiate query for each databse item and executes it.</p>
				<p>This mechanism allow wcomix to mantain and upgrade the database strucutre without having a bunch of queries to create the database from scratch and another bunch to upgrade each version combiantion.</p>
			</div>
		</div>
		<div class="Section">
			<span class="Title">Specs XML's specs</span>
			<div class="Paragraph">
				<p>Each XML must validated agaist a DTD file provided by xcomix which looks like this:</p>
				<pre class="brush: dtd;" title="Comments have been remove from the original DTD file.">
&lt;!ELEMENT table	(name,comment,columns,old_names?)&gt;
&lt;!ELEMENT index	(name,tablename,columns,non_unique?)&gt;

&lt;!ELEMENT columns	((column|columnname)+)&gt;

&lt;!ELEMENT column	(name,position,default?,null,column_type,comment,autoincrement?)&gt;

&lt;!ELEMENT old_names	(name+)&gt;

&lt;!ELEMENT columnname	(#PCDATA)&gt;
&lt;!ELEMENT tablename	(#PCDATA)&gt;
&lt;!ELEMENT name		(#PCDATA)&gt;
&lt;!ELEMENT comment	(#PCDATA)&gt;
&lt;!ELEMENT position	(#PCDATA)&gt;
&lt;!ELEMENT default	(#PCDATA)&gt;
&lt;!ELEMENT null		(#PCDATA)&gt;
&lt;!ELEMENT column_type	(#PCDATA)&gt;

&lt;!ELEMENT autoincrement	EMPTY&gt;
&lt;!ELEMENT non_unique	EMPTY&gt;</pre>
			</div>
		</div>
		<div class="Section">
			<span class="Title">Database Items</span>
			<span class="SubTitle">Tables</span>
			<div class="Paragraph">
				<p>Database table specifications may look like this:</p>
				<pre class="brush: xml;">&lt;?xml version="1.0"?&gt;
&lt;!DOCTYPE table SYSTEM "db.dtd"&gt;
&lt;table&gt;
	&lt;name&gt;my_table&lt;/name&gt;
	&lt;comment&gt;&lt;/comment&gt;
	&lt;columns&gt;
		&lt;column&gt;
			&lt;name&gt;mt_id&lt;/name&gt;
			&lt;position&gt;1&lt;/position&gt;
			&lt;null&gt;NO&lt;/null&gt;
			&lt;column_type&gt;int(11)&lt;/column_type&gt;
			&lt;comment&gt;&lt;/comment&gt;
			&lt;autoincrement/&gt;
		&lt;/column&gt;
		&lt;column&gt;
			&lt;name&gt;mt_name&lt;/name&gt;
			&lt;position&gt;2&lt;/position&gt;
			&lt;null&gt;NO&lt;/null&gt;
			&lt;column_type&gt;varchar(64)&lt;/column_type&gt;
			&lt;comment&gt;&lt;/comment&gt;
		&lt;/column&gt;
		&lt;column&gt;
			&lt;name&gt;mt_flag&lt;/name&gt;
			&lt;position&gt;3&lt;/position&gt;
			&lt;default&gt;N&lt;/default&gt;
			&lt;null&gt;NO&lt;/null&gt;
			&lt;column_type&gt;enum('Y','N')&lt;/column_type&gt;
			&lt;comment&gt;&lt;/comment&gt;
		&lt;/column&gt;
	&lt;/columns&gt;
&lt;/table&gt;</pre>
				<p>This specifies a table with 3 columns that may look like this (in MySQL):</p>
				<pre class="brush: sql;">create table wc_my_table (
	mt_id	int(11) not null primary key auto_increment,
	mt_name	varchar(64) not null,
	mt_flag enum('Y','N') not null default 'N'
)</pre>
			</div>

			<span class="SubTitle">Indexes</span>
			<div class="Paragraph">
				<p>Database indexes specifications may look like this (wc_comics-cmc_name.idx.xml is being used for this example):</p>
				<pre class="brush: xml;">&lt;?xml version="1.0"?&gt;
&lt;!DOCTYPE index SYSTEM "db.dtd"&gt;
&lt;index&gt;
	&lt;name&gt;cmc_name&lt;/name&gt;
	&lt;tablename&gt;comics&lt;/tablename&gt;
	&lt;columns&gt;
		&lt;columnname&gt;cmc_group&lt;/columnname&gt;
		&lt;columnname&gt;cmc_directory&lt;/columnname&gt;
		&lt;columnname&gt;cmc_name&lt;/columnname&gt;
	&lt;/columns&gt;
&lt;/index&gt;</pre>
				<p>This specifies a alterarion that may look like this (in MySQL):</p>
				<pre class="brush: sql;">create table wc_comics (

	.
	.
	.

	unique key cmc_name (cmc_group,cmc_directory,cmc_name)
)</pre>
				<p>This is not the actual query to be run.</p>
			</div>
		</div>
		<div class="Section">
			<span class="Title">Queries</span>
			<div class="Paragraph">
				<p>When wcomix uses this XML specifications and finds that something is broken,
				it generates an appropiate query to correct the different. This means, these
				queries may not be always the same and, the most cases, there will be no queries
				at all cause it's not normal to have a database change/difference.</p>
			</div>
		</div>
		<div class="Section">
			<span class="Title">Aggressive</span>
			<div class="Paragraph">
				<p>wcomix has a functionallity that allows it to destroy unspecified database
				objects like tables and indexes. This functionality can be activated by the
				installation wizard or just by changing a paramenter called {VA:$wcDatabase["aggressive"]}
				to true.</p>
			</div>
		</div>
	</body>
</html>
